Authorisatie en request headers

Om beveiligde endpoints te kunnen gebruiken, moet je eerst inloggen als gebruiker en een JWT-token ophalen. Deze token stuur je mee met ieder opvolgend request: dit bewijst je identiteit bij elke API-aanroep.

Jezelf authoriseren (inloggen)

De API biedt een standaard, onbeveiligd endpoint voor inloggen:

POST /api/login

Om in te loggen stuur je een POST-request met de inloggegevens van een bestaande gebruiker. Hierbij is het meesturen van het e-mailadres en wachtwoord verplicht:

{
  "email": "[email protected]",
  "password": "admin123"
}

Bij een succesvolle inlogpoging ontvang je een response met de user-informatie en een JWT-token:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "email": "[email protected]",
    "roles": [
      "admin"
    ]
  }
}

Dit token bevat gecodeerde informatie over de gebruiker, waaronder de rollen die aan de gebruiker zijn toegewezen. Dit kun je zien als het identiteitsbewijs van jouw gebruiker. Bij ieder verzoek dat je hierna zult maken, zul je telkens de token moeten meesturen om jezelf als het ware te 'legitimeren'.

Hoelang blijft een token geldig?

JWT-tokens hebben een vervaldatum- en tijd. Nadat een token is verlopen, zul je opnieuw moeten inloggen om een nieuwe token op te halen. De tokens die worden uitgegeven door deze API, zijn één uur geldig. Het is daarom belangrijk om in jouw code altijd eerst te checken of een token nog geldig is, voor je deze gebruikt om requests te maken. Dit voorkomt onnodige requests.

Wanneer je een gebruiker uit wil loggen, hoef je geen verzoek te doen naar de API. Je verwijdert simpelweg de token uit de localStorage.

Request headers

Om beveiligde endpoints aan te spreken nadat je een JWT-token hebt verkregen, heb je doorgaans twee belangrijke request headers nodig: de Authorization header en de novi-education-project-id header.

De Authorization header maakt gebruik van het Bearer-schema, gevolgd door een spatie en de token. Deze header ziet er zo uit:

Authorization: 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

Daarnaast bevat de novi-education-project-id header de unieke identifier (GUID) van je project:

'novi-education-project-id': 'ed30b6ec-f22a-4fa0-aceb-7aa8504e3e98'

Deze header is bedoeld als legitimatiebewijs voor jouw project. Op basis van deze GUID weet de API met welke projectomgeving en bijbehorende database er gewerkt moet worden. Zo zorg je ervoor dat je alleen toegang krijgt tot je eigen data, en niet tot die van anderen. Je project specifieke GUID wordt aan je verstrekt bij het aanmaken van jouw project, of je kunt deze terugvinden in je projectinstellingen.

In de volgende sectie zullen we zien hoe je de Swagger UI kunt gebruiken om je API te verkennen en te testen.